% HFR_Progs Matlab Directory Overview
% -----------------------------------
%
% This directory contains the meat of the HFR_Progs toolbox: the matlab
% code that does processing and analysis of HF radar data.  The
% basic philosophy and organization of the toolbox is discussed below.
% More documentation can be found in the individual directories and in
% each function.
%
%% ============================================================
% 
% Toolbox Philosophy
% ------------------
%
% This toolbox is used primarily to input HF radar radial current
% measurements and then generate total vectors currents, open-boundary modal
% analysis (OMA) currents, particle trajectories, etc. from these radial
% measurements.  Our method of storing such data in Matlab is to put all
% relevant variables, including metadata, inside Matlab structures.  For
% each type of data (radials, totals, trajectories), there is a particular
% structure format that is used to store the data. These structure formats
% have been standardized to facilitate easy interchange and maintenance of
% data.  For example, an empty structure for storing radial current
% measurements is generated by the function RADIALstruct in the radials
% directory.  Similarly for TUVstruct and TRAJstruct.
%
% In general, most users will not use the "struct" functions directly.
% Instead, we have created a set of functions that take in and spit out
% these structures.  For loading in radials data, there are two
% functions:
%
% loadRDLFile - loads the data in a CODAR RDL file into a RADIAL
%               structure
% criticalData2RADIAL - for non-RDL data this facilitates getting the
%                       basic variables in the correct places
%
% For creating totals, the makeTotals function in the totals directory is
% used.  
%
% For doing OMA fits (also stored in TUV structures), the following
% functions are available:
%
% fit_OMA_modes_to_totals - fits total currents data to modes
% fit_OMA_modes_to_radials - fits radials data
%
% For generating trajectories from totals or OMA data, the
% ptrack2TRAJstruct and generate_trajectories_from_OMA_fit are used.
%
% Variable dimensionality
% -----------------------
%
% Inside each structure, we have also strandardized the dimensionality of
% many of the variables.  For example, the U component of the velocity
% inside each TUV structure always has 1 row for each spatial grid point and
% 1 column for each timestep.  Similarly, the LonLat variable always has 1
% row for each grid point and 2 columns (one for longitude and one for
% latitude), and the TimeStamp variables has 1 row and 1 column for each
% timestep.  In general, the row dimension is always for space (where
% appropriate) and the column dimension is always for time (where
% appropriate) for all variables in all different types of structures.
%
% Although there is no way to enforce this standardization, using it
% means that one can take advantage of all sorts of functions that expect
% that dimensionality.  For example, the subsrefRADIAL and subrefTUV
% functions are used to splice out pieces of their respective structures
% (in analogy with the subsref matlab function, though ours function a
% bit different).  There are many other such examples.
%
% Extra variables
% ---------------
%
% Often one wants to store extra information along with the standard
% variables inside one of these data structures.  For example, the
% makeTotals function keeps track of the number of radials that went into
% each total vector.  To facilitate storing this information, inside each
% data structure there are a number of other sub-structures with names like:
%
% OtherMatrixVars
% OtherTemporalVars
% OtherSpatialVars
% OtherMetadata
%
% These sub-structures are used to store extra information with an
% understood dimensionality.  For example, variables inside OtherMatrixVars
% are understood to have one row for each grid point and one column for each
% timestep, while variables inside OtherSpatialVars have one row for each
% grid point and an arbitrary number of columns.  OtherMetadata is
% completely freeform.
%
% Functions like subsrefTUV know about these variables and treat them
% accordingly.
%
%% ============================================================
%
% Toolbox Organization
% --------------------
%
% Below is a list of directories and the type of functions they contain:
%
% analysis - some functions for doing specific types of analysis, such as
%            EOFs
% demo - this contains a toolbox demo function and some demo data
% drivers - this contains a couple of example functions for automating
%           specific tasks, such as generating hourly currents.
% external_matlab_packages - this contains other matlab toolboxes that are
%                            used by this toolbox, such as m_map.  See the
%                            general toolbox documentation for how to fill
%                            this directory.
% filters - functions in this directory filter and average total currents
%           data.
% general - this directory contains many low-level functions that are
%           used throughout the toolbox.
% gnome - functions for writing netCDF objects for use with gnome.  This
%         directory is somewhat out of step with the rest of the toolbox.
% OMA - functions for doing open-boundary modal analysis.
% plot - functions for plotting data, generally based on M_map.
% radials - function for inputing and manipulating radial current
%           measurements.
% tides - functions for doing tidal analysis.
% totals - functions for generating and manipulating total currents data.
% trajectories - functions for generating Lagrangian trajectories.
%
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% 	$Id: README.m 404 2007-04-04 22:17:45Z dmk $	
%
% Copyright (C) 2007 David M. Kaplan
% Licence: GPL (Gnu Public License)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

try
  [n,s] = HFR_Progs_version;
  disp([ 'HFR_Progs version: ' s ])
end
help README
